Release notes 2024
2024r11
Change to conditions for updating duration of time allocations in commercial API
In version 2024r8, the PUT /commercialBreakDuration call was added to the commercial API. It can update the duration of multiple time allocations on one day, channel and schedule version.
Previously, it was only possible to update time allocations that contained transmission events and had the All scheduled by interstitial integration property set to Yes. This meant that time allocations with only manually scheduled transmission events could not be updated.
From this version, this behaviour has changed. The PUT /commercialBreakDuration call can be used to update any time allocations, regardless of the value of the All scheduled by interstitial integration property.
Instead, elasticity influences updating. If the time allocations are elastic, the duration will be the sum of the individual commercials, so the duration is not updated by the call.
The YAML remains the same after this change.
2024r8
PUT /commercialBreakDuration call in commercial API
Using the commercial API, it is not possible to update the duration of time allocations with the POST /commercialPlaylist call. Even if it would be, the interstitial integration synchronization does not update time allocation durations either because the existing calls update schedule inbox objects that do not directly affect time allocations.
However, previously, if the external system already knew the time allocations would be longer or shorter than defined in the schedule, it could not send this update to Mediagenix Base platform.
Therefore, from this version, the PUT /commercialBreakDuration call has been added to the commercial API. It can update the duration of multiple time allocations on one day, channel and schedule version.
The call will map the time allocations on either the block label using the breakId attribute, or the external block label using the externalBreakId attribute. Only the one defined on the interstitial integration definition has to be provided.
It is only possible to update time allocations that have transmission events and have the All scheduled by interstitial integration property set to Yes.
An example of the body:
{
"channelId": "MGX",
"startDate": "2024-09-01",
"scheduleVersion": "Active",
"timeAllocations": [
{
"breakId": "00001010",
"externalBreakId": "010101010",
"duration": "00:05:01"
},
{
"breakId": "00000101",
"externalBreakId": "00002222,
"duration": "00:03:14"
}
]
}API developers
The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.
At line 164, the /commercialBreakDuration path was added.
At line 856, the TimeAllocationForBreakDuration schema was added.
At other lines, some descriptions were updated.
For easier viewing, the YAMLs can also be compared here: https://www.textcompare.org/yaml
Predicted ratings in business API
In version 2024r8, predicted ratings calculation was introduced.
Once the predicted ratings are calculated and the actual ratings are imported, the results can be used in the commercial API.
In the commercial API, the GET /breakSchedule call returns the break schedule for one complete broadcast day for all time allocations that are part of a published interstitial integration definition.
In version 2022r7, the predictedRatings array returned the predicted TRP ratings of a time allocation. (See 2022r7) These could be entered in the trailer grid using the Edit predicted ratings… command.
From this version, the predictedRatings array will return the final predicted ratings of a time allocation, which can be seen in the predicted ratings navigator.
An example of the response of the GET /breakSchedule call after generating predicted ratings:
{
"transmissionId": "9501319722",
"startTime": "11:00:00",
"startTimeUTC": "10:00:00",
"announcedStartTime": "11:00",
"lockedStartTime": false,
"duration": "00:34:00",
...
"contractNumber": null,
"timeAllocations": [
{
"breakId": null,
"externalBreakId": null,
"startTime": "10:58:00",
"duration": "00:01:00",
"type": "trailer",
"position": "Start",
"startTimeUTC": "09:58:00",
"readOnly": true,
"title": "I MAY DESTROY YOU - Social Media Is a Great Way to Connect - - Auto promotion",
"sequenceNumber": 1,
"regional": false,
"masterBreakId": null,
"predictedRatings": [
{
"rating": 0.0952,
"targetGroup": "Teens"
},
{
"rating": 3.6560,
"targetGroup": "Adults"
},
{
"rating": 6.7509,
"targetGroup": "Kids"
},
{
"rating": 2.0556,
"targetGroup": "60+"
}
]
},2024r7
Update media assets of commercials using commercial API
The commercial API supports interstitial integration between Mediagenix Base platform and an external system (RN-4359).
Previously, the POST /commercialPlaylist, POST /commercial and PUT /commercialBreak calls allowed to create media assets, but were not be able to update it. This was because it was assumed that the MAM system became the owner after creation in the Mediagenix Base platform.
For example, for the following POST /commercial call body:
{
"duration": "00:01:00",
"interstitialId": "9501012904",
"title": "The Eras Tour",
"mediaAssets": [
{
"mediaAssetId": "9501012906",
"frameRate": "25fps",
"label": "TET023072024",
"preferred": false,
"kind": "ANTENNE"
}
]
}It was checked if the media asset referenced in the mediaAssetId already existed:
-
If so, the media asset information in the payload was ignored and the BAPI service would log: Media asset information was ignored. The commercial API can only create media assets.
-
If it did not exist, the media asset was created.
However, for some customers, the commercial integration system should be allowed to update media assets. Therefore, from this version, the message above will not appear in the service anymore and a media asset can be updated using the mediaAssets array in the body of the POST /commercialPlaylist, POST /commercial and PUT /commercialBreak calls.
The YAML did not change for this adjustment.
2024r3
Time allocation and transmission event remarks in commercial API
The commercial API enables interstitial integration using the business API.
The POST /commercialPlaylist and PUT /commercialBreak calls are used to create and update the interstitial blocks and clips that will be synchronised.
From this version, the remarks on time allocations and transmission events in WHATS'ON can be synchronised from an external system using interstitial integration (RN-6314).
To support an update to the remarks also from the API, the remarks attribute has been added to the timeAllocations array and events array of the POST /commercialPlaylist and PUT /commercialBreak calls.
An example of the POST /commercialPlaylist body:
{
"channelId": "MGX",
"startDate": "2024-05-01",
"definitionId": "Comm",
"timeAllocations": [
{
"breakId": "000018",
"startTime": "05:56:00",
"startTimeUTC": "03:56:00",
"type": "commercial",
"remarks": "filled by API",
"events": [
{
"spotId": "INTINTEG01",
"eventId": "INTINTEG01",
"duration": "00:15:00",
"sequenceNumber": 1,
"remarks": "filled by API",
"commercial": {
"interstitialId": "INTINTEG01",
"identification": "INTINTEG01",
"duration": "00:00:20",
"title": "MARINE TRAFFIC",
}
}
]
}
]
}When the Use external remarks column on the interstitial integration definition (RN-6314) is set to No, and the remarks are changed using the API, the remarks on the interstitial blocks or interstitial clips are still updated but they will not trigger a change for synchronisation with the time allocations and transmission events.
API developers
For API developers, the following has changed in the YAML:
-
A note has been added at line 114 to the description of the /commercialBreak put call.
-
At line 827, the following is added to the TimeAllocationForPlaylist schema:
remarks:
type: string
description: Remarks for the time allocation -
At line 854, the following is added to the Event schema:
remarks:
type: string
description: Remarks for the time allocation -
At line 860, a different schema is referenced.
-
At line 918, a new CommercialForPlaylist schema is added.
For easier viewing, the YAMLs can also be compared here: https://www.textcompare.org/yaml
Ratings in POST /commercial call of commercial API
It is possible to create commercials and their media assets using the POST /commercial call of the commercial API.
From this version, it is possible to add parental ratings when creating media assets. For this, the ratings array has been added to the mediaAssets part of the POST /commercial call.
The array contains the following attributes:
-
regulator:
Maps to the Regulator field in the PARENTAL RATINGS PER REGULATOR list on the Parental rating tab on media assets in WHATS'ON Base. The field takes its values from the WOnRegulator drop-down list. -
rating:
Maps to the Parental rating field, with values from the WOnProgramCertification drop-down list. -
reason:
Maps to the Reason text field. -
status:
Maps to the Parental rating status field, with values from the WOnProgramCertificationState drop-down list.
An example of the array in the body:
"ratings": [
{
"regulator": "ofcom",
"rating": "16+",
"reason": "Explicit",
"status": "Approved"
},The YAML has been updated for this change. It can be retrieved by using the GET /api call.
API developers
For API developers, the following has changed in the YAML:
-
At line 1015, the ratings array has been added to the MediaAssets schema
For easier viewing, the YAMLs can also be compared here: https://www.textcompare.org/yaml